Repository navigation
perf(hub): anonymous joins share one cached picture, then the batches since (#2519) - #2589
Merged
Merged
Conversation
… then the batches since (#2519) A token-less page hello is answered from a join cache: the snapshot stringified once per negotiated form and the log list, rebuilt every 2 s or after a recovery, followed by every ring batch after it. SIM_JOIN_CACHE=0 turns it off. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…all joiners (#2519) A world's first batch after boot can hold megabytes of log; each cached joiner re-stringified it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
genekogan
marked this pull request as ready for review
November 16, 2026 10:41
Contributor
Proof check:
|
| Check | Status | Detail |
|---|---|---|
| problem statement | ok | present |
| linked issue | ok | #2519 |
| acceptance | ok | 5/5 met |
| carried from the issue | ok | all 5 issue criteria present |
| self-audit | ok | checks, failed attempts, long tail and limits filled |
Acceptance criteria
| Criterion | Status | Evidence | |
|---|---|---|---|
| [x] | A1 Oracle test: two product clients (Connection and Replica) join the |
met | node --test apps/server/src/hub-join-cache.test.ts -> test "A1" passes: the cached client gets the shared picture buil |
| [x] | A2 A join during the 2 s after a recovery, and a resync, both converge |
met | same file, test "A2" passes: a picture built 0.5 s before a recovery is not used by a join 0.5 s after it (the joiner ge |
| [x] | A3 Every hub test passes unmodified with the flag off and on. | met | every apps/server/src/*.test.ts constructing a Hub (25 files) plus the new one: `SIM_JOIN_CACHE=1 node --test --test |
| [x] | A4 Main-thread time per anonymous join falls by at least 70 % against Ste | met | BRAIN_MODE=fake node step0.ts 30 (the Step 0 probe described below: bootEden + a real Hub, timing Hub.onMessage |
| [x] | A5 viewers --viewers 0,200 --arrive-per-sec 20 --souls 24 --act-sec 10, |
met | six timed runs, all succeeded (even off, [even |
Proof links: 0 video, 0 image, no proof.json.
Updated on every edit, push, label and review. How to fill it: .claude/skills/journal/SKILL.md. T3-T4 also need the maintainer's sign-off (tools/proof/gate.mjs). A maintainer can waive with the proof:waived label.
Member
Author
|
Merge train: this PR is behind Conflicting files:
Resolution attempt: Rebase onto |
# Conflicts: # docs/architecture/load.md
genekogan
enabled auto-merge
November 16, 2026 12:08
This was referenced Nov 16, 2026
Open
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
Every anonymous viewer that joins a world gets its own snapshot built on the world's thread: on Eden 2026 about 50 ms of main thread per join (Step 0 below), so 20 arrivals a second cost the world about a whole second of thread per second. This makes an arriving anonymous viewer cheap: the heavy first picture is built once every two seconds, however many arrive. Closes #2519.
Acceptance
ConnectionandReplica) join the same world, one with the cache off and one on, while 6 scripted Souls walk. Zero resyncs on either; equalreplica.viewHashat the same heartbeat sequence for 60 s; equal sets of log sequences, talk ids, play sequences and take end ticks. — evidence:node --test apps/server/src/hub-join-cache.test.ts-> test "A1" passes: the cached client gets the shared picture built 1.5 s (30 ticks) earlier plus exactly the batches after it, in order; then 1,200 ticks (60 s) of 6 walking Souls; 0 resyncs on both, 0 mismatches, viewHash equal at every common heartbeat (>= 10), equal log sequences (from the later client's first one), talk ids, play sequences and take end ticks. Mutation check: replaying from the cache's seq + 2, or not replaying, fails it (the second through the behavioural oracle alone, with the structural asserts removed).resync, both converge (same oracle). — evidence: same file, test "A2" passes: a picture built 0.5 s before a recovery is not used by a join 0.5 s after it (the joiner gets a picture of now); aresync30 s later is answered from the world as it is at the request; after 60 s, the same oracle with resyncs (0, 1).apps/server/src/*.test.tsconstructing aHub(25 files) plus the new one:SIM_JOIN_CACHE=1 node --test --test-concurrency=4 <26 files>-> 163 pass, 0 fail;SIM_JOIN_CACHE=0 ...-> 163 pass, 0 fail.BRAIN_MODE=fake node step0.ts 30(the Step 0 probe described below:bootEden+ a realHub, timingHub.onMessageper hello) onagent/2519-meas-basethen on base + this branch, back to back, two runs each (bar declared on the issue: candidate mean <= 0.30 x base mean) -> final head: base 50.6 / 48.5 ms, candidate 7.7 / 7.0 ms mean (ratios 0.15 / 0.14, -85 %); p50 44.9 / 43.6 -> 1.1 / 1.1 ms. First candidate commit (before the batch strings were shared): 53.5 / 47.7 -> 14.9 / 13.7 ms (0.28 / 0.29).viewers --viewers 0,200 --arrive-per-sec 20 --souls 24 --act-sec 10, 2 repeats, flag off and on, reported side by side; and the same with--dwell-sec 60(joins never stop), which is the case this task is for. — evidence: six timed runs, all succeeded (even off, even on, dwell off, dwell on, uneven off, uneven on), side by side in the A5 table below. Cache on: the clock kept 0.93 to 0.99 in all 6 repeats, and first motion p95 stayed at or below 4.8 s. Cache off: 3 of 6 repeats collapsed (clock 0.70, 0.22 and 0.57; the last world restarted). The issue's expectation (clock >= 0.95 and heap within 150 MB of zero viewers) holds in 3 of 6 candidate repeats on both counts, and in 1 of 6 base repeats.Step 0 (premise check; posted on the issue before the runs)
Probe: one in-process Eden 2026 world (
bootEden, fake minds), a realHubon a local socket, 30 anonymous joins with the page's URL hello (anonymousHello(true)), one world tick between joins. Timer:performance.now()from the hello enteringHub.onMessageto its return after the join's last message is handed to the socket. Shared workstation, load average 4 to 15 on 16 cores, recorded per run. No timed-run command runs a probe, so this one is local; the ratio is what is scored.host.snapshotView()loglist (tailEvents(150)+publicEvent)Entity table: 5,168 entries, 1.72 MB as JSON, 410 KB in the column form.
A5 runs (souls-timed,
timed-run.ymlfromagent/2519-meas-base, repeats 2)Base (cache off) = origin/main 3d8da8a + merges of the two V0 fixes (PRs 2583, 2586) and the viewers bench (PR 2572), as the coordinator's measurement note requires. Candidate (cache on) = that + this branch at ec67c5a. The second commit here only shares replayed batch strings, so it can only lower per-join cost. The runner cannot set environment, so "flag off" is the base ref. All arms share
--viewers 0,200 --arrive-per-sec 20 --souls 24 --act-sec 10. Runner: 48 CPUs, world on 2 physical cores, load generator on the rest. Host load average before and after each run: 7 to 20 (in each run's REPORT.md).Figures are for the 200-viewer window of each repeat. Clock = tick service. Heap Δ = main heap max at 200 viewers minus the max in the 0-viewer window. Acts = achieved of 288 intended. CPU = world CPU in cores.
--arrive-burst 100@30), offHow to read it:
Proof
Tier: T1
Deviations from the design
useSoulsonLog) keeps time order.since(the page's entry join). A token-less reconnect too far behind keeps its fresh snapshot (its reason text differs, and it is rare).resyncis unchanged (always fresh), which meets "answered from a cache built after the request arrived".Self-audit
npx tsc --noEmit -p apps/server-> clean;node --test apps/server/src/hub-join-cache.test.ts-> 2 pass; A3 runs above -> 163/163 both ways;node .github/scripts/guards.mjs scrub --base origin/main-> 0 problems;node tools/changelog/compile.mjs --check-> valid.docs/architecture/load.md(anonymous socket joins share one picture, andSIM_JOIN_CACHE).Changelog
changes/2519-join-cache.md(perf).Risk
A cached joiner could reach a different replica than a fresh one; the A1/A2 oracle covers walking Souls, recoveries and resyncs, and the client's heartbeat check would resync it in any case. Signed-in joins, resumes and resyncs are untouched. Roll back with
SIM_JOIN_CACHE=0in the world's environment, or a revert.Time: started 09:49 UTC. Code, tests and A4 were done by 10:10. A5 was scored from 10:40 to 10:50. About 0.5 h of work against a 3 h ceiling; the 30 min wait on the runners is not counted.
Outside Touches: none.
🤖 Generated with Claude Code